---
description: Hasura Cloud and Hasura Enterprise read replicas
title: 'Cloud and Enterprise Edition: Read replicas on Hasura Cloud'
keywords:
  - hasura
  - docs
  - cloud
  - enterprise
  - read replicas
  - connections
  - pool
sidebar_label: Read replicas
sidebar_position: 1
# sidebar_class_name: cloud-and-enterprise-icon
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Thumbnail from '@site/src/components/Thumbnail';
import HeadingIcon from '@site/src/components/HeadingIcon';
import ProductBadge from '@site/src/components/ProductBadge';

# Read Replicas

<ProductBadge pro ee self />

## Introduction

Hasura Cloud and Hasura Enterprise can route queries and subscriptions across _read replicas_ while sending all
mutations and Metadata API calls to the primary.

This works by selecting a read replica instance at random. Hasura does not
perform any kind of load balancing across the replicas. The random function used
has a uniform distribution, and so over time, queries will distribute uniformly
across all replica instances.

## Adding read replica URLs

### Postgres

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

Head to `Data -> Manage -> <db-name> -> Edit`

<Thumbnail
  src="/img/databases/read-replicas/connect-db-with-replica.png"
  alt="Connect database with read replica"
  width="1000px"
/>

</TabItem>
<TabItem value="cli" label="CLI">

You can add _read replicas_ for a database by adding their config to the `/metadata/databases/database.yaml` file:

```yaml {11-17}
- name: <db-name>
  kind: postgres
  configuration:
    connection_info:
      database_url:
        from_env: <DATABASE_URL_ENV>
      pool_settings:
        idle_timeout: 180
        max_connections: 50
        retries: 1
    read_replicas:
      - database_url:
          from_env: <DATABASE_REPLICA_URL_ENV>
        pool_settings:
          idle_timeout: 180
          max_connections: 50
          retries: 1
```

Apply the Metadata by running:

```yaml
hasura metadata apply
```

</TabItem>
<TabItem value="api" label="API">

You can add _read replicas_ for a database using the
[pg_add_source](/api-reference/metadata-api/source.mdx#metadata-pg-add-source) Metadata API.

```http {16-27}
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type":"pg_add_source",
  "args":{
    "name":"<db_name>",
    "replace_configuration":true,
    "configuration":{
      "connection_info":{
        "database_url":{
          "from_env":"<DATABASE_URL_ENV>"
        }
      },
      "read_replicas":[
        {
          "database_url":{
            "from_env":"<DATABASE_REPLICA_URL_ENV>"
          },
          "pool_settings":{
            "retries":1,
            "idle_timeout":180,
            "max_connections":50
          }
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

:::info For existing v1.3 projects

If you have configured your Postgres instances with replicas; then the replica URLs can be added to Hasura using the
following environment variable in your project ENV Vars tab:

```bash
HASURA_GRAPHQL_READ_REPLICA_URLS=postgres://user:password@replica-host:5432/db
```

In the case of multiple replicas, you can add the URLs of each replica as comma-separated values.

Additional environment variables for _read replicas_ specifically:

`HASURA_GRAPHQL_CONNECTIONS_PER_READ_REPLICA`

`HASURA_GRAPHQL_STRIPES_PER_READ_REPLICA`

**NOTE: Please note that the above environment variables are only available for v1.3 projects and are no longer
supported for v2.0 and above projects.**

:::

### MS SQL Server

<Tabs groupId="user-preference" className="api-tabs">
  <TabItem value="console" label="Console">

Head to `Data -> Manage -> <db-name> -> Edit`

<Thumbnail
  src="/img/databases/read-replicas/connect-db-with-replica-mssql.png"
  alt="Connect database with read replica"
  width="1000px"
/>

</TabItem>

<TabItem value="cli" label="CLI">

You can add _read replicas_ for a database by adding their config to the `/metadata/databases/database.yaml` file:

```yaml {10-15}
- name: <db-name>
  kind: mssql
  configuration:
    connection_info:
      connection_string:
        from_env: <DATABASE_URL_ENV>
      pool_settings:
        idle_timeout: 180
        max_connections: 50
    read_replicas:
      - connection_string:
          from_env: <DATABASE_REPLICA_URL_ENV>
        pool_settings:
          idle_timeout: 25,
          max_connections: 100
```

Apply the Metadata by running:

```yaml
hasura metadata apply
```

</TabItem>
<TabItem value="api" label="API">

You can add _read replicas_ for a database using the
[mssql_add_source](/api-reference/metadata-api/source.mdx#mssql-add-source) Metadata API.

```http {19-29}
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type":"mssql_add_source",
  "args":{
    "name":"<db_name>",
    "replace_configuration":true,
    "configuration":{
      "connection_info":{
        "connection_string":{
          "from_env":"<DATABASE_URL_ENV>"
        },
        "pool_settings":{
          "max_connections":50,
          "idle_timeout":180
        },
        "read_replicas":[
          {
            "connection_string":{
              "from_env":"<DATABASE_REPLICA_URL_ENV>"
            },
            "pool_settings":{
              "idle_timeout":180,
              "max_connections":50
            }
          }
        ]
      }
    }
  }
}

```

</TabItem>
</Tabs>
